@azure/storage-blob

export

export

export

export

export

export

export

Downloads an Azure Blob in parallel to a buffer. Offset and count are optional, pass 0 for both to download the entire blob.

export

URL encode and escape strategy for JSv10 SDKs

When customers pass a URL string into XXXURL classes constrcutor, the URL string may already be URL encoded or not. But before sending to Azure Storage server, the URL must be encoded. However, it's hard for a SDK to guess whether the URL string has been encoded or not. We have 2 potential strategies, and chose strategy two for the XXXURL constructors.

Strategy One: Assume the customer URL string is not encoded, and always encode URL string in SDK.

This is what legacy V2 SDK does, simple and works for most of the cases.

• When customer URL string is "http://account.blob.core.windows.net/con/b:", SDK will encode it to "http://account.blob.core.windows.net/con/b%3A" and send to server. A blob named "b:" will be created.
• When customer URL string is "http://account.blob.core.windows.net/con/b%3A", SDK will encode it to "http://account.blob.core.windows.net/con/b%253A" and send to server. A blob named "b%3A" will be created.

But this strategy will make it not possible to create a blob with "?" in it's name. Because when customer URL string is "http://account.blob.core.windows.net/con/blob?name", the "?name" will be treated as URL paramter instead of blob name. If customer URL string is "http://account.blob.core.windows.net/con/blob%3Fname", a blob named "blob%3Fname" will be created. V2 SDK doesn't have this issue because it doesn't allow customer pass in a full URL, it accepts a separate blob name and encodeURIComponent for it. We cannot accept a SDK cannot create a blob name with "?". So we implement strategy two:

Strategy Two: SDK doesn't assume the URL has been encoded or not. It will just escape the special characters.

This is what V10 Blob Go SDK does. It accepts a URL type in Go, and call url.EscapedPath() to escape the special chars unescaped.

• When customer URL string is "http://account.blob.core.windows.net/con/b:", SDK will escape ":" like "http://account.blob.core.windows.net/con/b%3A" and send to server. A blob named "b:" will be created.
• When customer URL string is "http://account.blob.core.windows.net/con/b%3A", There is no special characters, so send "http://account.blob.core.windows.net/con/b%3A" to server. A blob named "b:" will be created.
• When customer URL string is "http://account.blob.core.windows.net/con/b%253A", There is no special characters, so send "http://account.blob.core.windows.net/con/b%253A" to server. A blob named "b%3A" will be created.

This strategy gives us flexibility to create with any special characters. But "%" will be treated as a special characters, if the URL string is not encoded, there shouldn't a "%" in the URL string, otherwise the URL is not a valid URL. If customer needs to create a blob with "%" in it's blob name, use "%25" insead of "%". Just like above 3rd sample. And following URL strings are invalid:

• "http://account.blob.core.windows.net/con/b%"
• "http://account.blob.core.windows.net/con/b%2"
• "http://account.blob.core.windows.net/con/b%G"

Another special character is "?", use "%2F" to represent a blob name with "?" in a URL string.

Strategy for containerName, blobName or other specific XXXName parameters in methods such as BlobURL.fromContainerURL(containerURL, blobName)

We will apply strategy one, and call encodeURIComponent for these parameters like blobName. Because what customers passes in is a plain name instead of a URL.

see

https://docs.microsoft.com/en-us/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata

see

https://docs.microsoft.com/en-us/rest/api/storageservices/naming-and-referencing-shares--directories--files--and-metadata

export

Generates a SASQueryParameters object which contains all SAS query parameters needed to make an actual REST request.

see

https://docs.microsoft.com/en-us/rest/api/storageservices/constructing-an-account-sas

memberof

IAccountSASSignatureValues

Creates an instance of SASQueryParameters.

Only accepts required settings needed to create a SAS. For optional settings please set corresponding properties directly, such as permissions, startTime and identifier.

WARNING: When identifier is not provided, permissions and expiryTime are required. You MUST assign value to identifier or expiryTime & permissions manually if you initial with this constructor.

example

// Generate service level SAS for a container const containerSAS = generateBlobSASQueryParameters({ containerName, // Required permissions: ContainerSASPermissions.parse("racwdl").toString(), // Required startTime: new Date(), // Required expiryTime: tmr, // Optional. Date type ipRange: { start: "0.0.0.0", end: "255.255.255.255" }, // Optional protocol: SASProtocol.HTTPSandHTTP, // Optional version: "2016-05-31" // Optional }, sharedKeyCredential // SharedKeyCredential ).toString();

example

// Generate service level SAS for a container with identifier // startTime & permissions are optional when identifier is provided const identifier = "unique-id"; await containerURL.setAccessPolicy(Aborter.none, undefined, [ { accessPolicy: { expiry: tmr, // Date type permission: ContainerSASPermissions.parse("racwdl").toString(), start: now // Date type }, id: identifier } ]);

const containerSAS = generateBlobSASQueryParameters( { containerName, // Required identifier // Required }, sharedKeyCredential // SharedKeyCredential ).toString();

example

// Generate service level SAS for a blob const blobSAS = generateBlobSASQueryParameters({ containerName, // Required blobName, // Required permissions: BlobSASPermissions.parse("racwd").toString(), // Required startTime: new Date(), // Required expiryTime: tmr, // Optional. Date type cacheControl: "cache-control-override", // Optional contentDisposition: "content-disposition-override", // Optional contentEncoding: "content-encoding-override", // Optional contentLanguage: "content-language-override", // Optional contentType: "content-type-override", // Optional ipRange: { start: "0.0.0.0", end: "255.255.255.255" }, // Optional protocol: SASProtocol.HTTPSandHTTP, // Optional version: "2016-05-31" // Optional }, sharedKeyCredential // SharedKeyCredential ).toString();

export

Creates an instance of SASQueryParameters. WARNING: identifier will be ignored when generating user delegation SAS, permissions and expiryTime are required.

example

// Generate user delegation SAS for a container const userDelegationKey = await serviceURL.getUserDelegationKey(aborter, startTime, expiryTime); const containerSAS = generateBlobSASQueryParameters({ containerName, // Required permissions: ContainerSASPermissions.parse("racwdl").toString(), // Required startTime, // Required. Date type expiryTime, // Optional. Date type ipRange: { start: "0.0.0.0", end: "255.255.255.255" }, // Optional protocol: SASProtocol.HTTPSandHTTP, // Optional version: "2018-11-09" // Must >= 2018-11-09 to generate user delegation SAS }, userDelegationKey, // UserDelegationKey accountName ).toString();

export

export

export

export

export

export

export

export

"8.8.8.8" or "1.1.1.1-255.255.255.255"

export

export

"bytes=255-" or "bytes=0-511"

export

export

export

export

export

throws

{RangeError} If buffer size is not big enough.

export

Uploads a browser Blob/File/ArrayBuffer/ArrayBufferView object to block blob.

When buffer length <= 256MB, this method will use 1 upload call to finish the upload. Otherwise, this method will call stageBlock to upload blocks, and finally call commitBlockList to commit the block list.

export

Uploads a local file in blocks to a block blob.

When file size <= 256MB, this method will use 1 upload call to finish the upload. Otherwise, this method will call stageBlock to upload blocks, and finally call commitBlockList to commit the block list.

export

Uploads a Node.js Readable stream into block blob.

PERFORMANCE IMPROVEMENT TIPS:

• Input stream highWaterMark is better to set a same value with bufferSize parameter, which will avoid Buffer.concat() operations.

export